% Manual for the DENCHAR program
%
% To generate the printed version:
%
% latex denchar
% latex denchar
% [ dvips denchar ] 
%
%   Javier Junquera  Feb 04, 2002
%   Pablo Ordejon    Jul 02, 2003
%   Pablo Ordejon    2004  -- multiple k-points
%   Alberto Garcia,  2006-2012 -- fixes, use WFSX format
%   Alberto Garcia,  2016 -- New files for 3D mode
%   Alberto Garcia,  2019 -- NC/SOC support, stream mode


\documentstyle[11pt]{article}

\tolerance 10000
\textheight 22cm
\textwidth 16cm
\oddsidemargin 1mm
\topmargin -15mm

\baselineskip=14pt
\parskip 5pt
\parindent 1em

\begin{document}

% TITLE PAGE --------------------------------------------------------------

\begin{titlepage}

\begin{center}

\vspace{1cm}

{\huge {\sc User's Guide}}

\vspace{4cm}

{\Huge {\bf {\sc Denchar} 3.0} }

\vspace{0.5 cm}

{\Large {\it - A program to plot charge densities and wave functions 
in real space -}}


\vspace{3cm}
{\Large Javier Junquera}
\vspace{1cm}
{\Large Pablo Ordej\'on, Alberto Garc\'{\i}a}
\end{center}

\end{titlepage}

% END TITLE PAGE --------------------------------------------------------------

\tableofcontents

\newpage


\section{INTRODUCTION}

The program {\sc Denchar} calculates charge densities and/or electronic 
wavefunctions in real space, from the output generated by {\sc Siesta}.

The code has two different modes of usage:

\begin{itemize}

\item{\bf 2D mode}, where the charge density and/or electronic
wavefunctions are printed on a regular grid of points contained
in a 2D plane (specified by the user). 
The results are printed in a file, in the form
of a list $x_i$,$y_i$,$f(x_i,y_i)$, where $f$ is either a
charge density or a wavefunction, and $x_i$, $y_i$ are the coordinates
of each grid point in the plane, refered to a cartessian system
where the $x$ and $y$ axes are contained in the plane and $z$ is
perpendicular to it.
This file can be used to plot contour maps by means of
2D graphics packages.

\item{\bf 3D mode}, where the charge density and/or electronic
wavefunctions are printed on a regular grid of points in 3D.
The results are printed in a file in Gaussian Cube
format, that can be visualized by means of standard programs
such as {\sc Moldel} and {\sc Molekel}. The system of coordinates
($x$, $y$, $z$) used to produce the grid is orthonormal, and 
does not need to be the same as the one of {\sc Siesta}, but
can be defined by the user.

\end{itemize}

The main features of {\sc Denchar} are:
\begin{itemize}

\item
Flexibility for defining the plane (in 2D mode) or the
coordinates system (in 3D mode) where the charge density and/or
wavefunctions will be computed.
Possible options are: the normal vector, 
two lines contained in the plane,
three points included in the plane,
or three atoms contained in it.
The input variables used to define the plane in 2D and the
coordinates system in 3D are the same. In the latter case, the
$x$ and $y$ axes are those defining the plane, and $z$ is
the perpendicular axis to them.

\item
For spin-unpolarized calculations, the fully self-consistent charge and
the difference between the SCF charge density and the superposition of atomic
densities are calculated. In this way, we can study how the chemical bonds 
change the charge distribution.
 
\item
For spin-polarized calculations, the magnetization (difference between
the charge density for spin up and down) is calculated.

\item
When wavefunctions are computed, each wavefunction present in the
file produced by {\sc Siesta} is printed on a different file, 
so that they can be plotted individually. Real and imaginary
parts are written independently.

\end{itemize}

\section{HOW TO COMPILE AND RUN THE PROGRAM}

\subsection{Compilation}

The code for {\sc Denchar} is now in the top source directory. Just
type {\tt make denchar} there to compile it.


\subsection{Running the code}

 {\sc Denchar} needs some information that will be supplied by {\sc Siesta}. 
 The first thing we must do is to run {\sc Siesta} for 
 the system we are interested in,
 setting up variable WriteDenchar to true. 
 In this way {\sc Siesta} will generate
 two files called {\it SystemLabel}.PLD and {\it SystemLabel}.DIM
 where information 
 needed to plot the charge density and/or wavefunctions 
 in real space is dumped. You also need to have the files which
 contain the information about the basis set for each species
 in your system: {\it ChemicalSpecies}.ion (one for each
 chemical species), which
 are also generated by  {\sc Siesta}.
 Finally, you will need the file containing the
 density matrix {\it SystemLabel}.DM if you wish to plot
 the charge density, or that containing the wavefunction
 coefficients {\it SystemLabel}.WFSX if you want to plot
 wavefunctions. These files need to be present in the
 directory where you are running {\sc Denchar} (let's call it
 $\sim$/denchar-run).

 Go into the directory where {\sc Denchar} will run:

 {\tt \# cd $\sim$/denchar-run}

 Copy all the required files into this directory; if you
 have run {\sc Siesta} in directory $\sim$/siesta/RUN:

 {\tt \# cp $\sim$/siesta/RUN/{\it SystemLabel}.PLD .}

 {\tt \# cp $\sim$/siesta/RUN/{\it SystemLabel}.DIM .}

 {\tt \# cp $\sim$/siesta/RUN/*.ion .}

 {\tt \# cp $\sim$/siesta/RUN/{\it SystemLabel}.DM .}

 {\tt \# cp $\sim$/siesta/RUN/{\it SystemLabel}.WFSX .}

(NOTE: Modern versions of {\sc Siesta} produce different kinds
of WFSX files: 
\begin{itemize}
\item {\it SystemLabel}.fullBZ.WFSX : for full PDOS or COOP/COHP
  analysis.
\item {\it SystemLabel}.bands.WFSX : for ``fatbands'' analysis.
\item {\it SystemLabel}.selected.WFSX : holding selected k-point information.
\end{itemize}
Be sure to copy or link the right version to  {\it SystemLabel}.WFSX.)

 Copy or link the executable file to the directory
 where you intend to run  {\sc Denchar}, and that
 contains the files described above:

 {\tt \# ln -s $\sim$/siesta/Util/Denchar/Src/denchar . }

 Edit an input file for {\sc Denchar}, {\it input}.fdf, following the 
 instructions given in Section \ref{cap:input}. Then,
 run  {\sc Denchar} reading {\it input}.fdf on
 standard input:


 {\tt \# denchar < {\it input}.fdf } 


 The output with the values of charges and wavefunctions
 in the grid is dumped into files, which will be described
 in Section \ref{cap:output}. Some informative output is
 algo given on standard output.

\section{INPUT DATA FILE}
\label{cap:input} 

The input data file is written in an special format called FDF, developed
by Alberto Garc\'{\i}a and Jos\'e M. Soler (see {\sc Siesta} USER'S GUIDE).
It contains all the parameters needed to specify the details
of the run and to define the plane or coordinates system.
Here is a description of the variables that you can define in your 
{\sc Denchar} input files,
with their data types and default values.

\vspace{5pt}
\subsection{General descriptors}

\begin{description}
\itemsep 10pt
\parsep 0pt

\item[{\bf SystemLabel}] ({\it string}): 
A {\bf single} word (max. 20 characters {\bf without blanks})
containing a nickname of the system, used to name output files. 
{\bf It must be the same that you use when you run {\sc Siesta}!!}

{\it Default value:} siesta

\item[{\bf NumberOfSpecies}] ({\it integer}):
Number of different atomic species in the simulation.
Atoms of the same species, but with a different
pseudopotential or basis set are counted as different species.
Use the same value as in the {\sc Siesta} run.

{\it Default value:} There is no default. You must supply this variable.


\item[{\bf ChemicalSpeciesLabel}] ({\it data block}):
It specifies the different chemical species\index{species} that are present,
assigning them a number for further identification.
Use the same as you did in {\sc Siesta}.

{\it Use:} This block is mandatory.

{\it Default:} No default.

\item[{\bf Denchar.TypeOfRun}] ({\it string}): 
Specifies if you want to represent your charge density
and/or wavefunctions in 2D or 3D.

{\it Default value:} 2D

\item[{\bf Denchar.PlotCharge}] ({\it logical}): 

Specifies if you want to calculate and plot a charge density
in real space.

{\it Use:} Either {\bf Denchar.PlotCharge} or
{\bf Denchar.PlotWaveFunctions} must be .TRUE.
If set to .TRUE., file {\it SystemName}.DM should
be present.

{\it Default value:} .FALSE.

\item[{\bf Denchar.PlotWaveFunctions}] ({\it logical}): 

Specifies if you wand to calculate and plot wavefunctions
in real space.

{\it Use:} Either {\bf Denchar.PlotCharge} or
{\bf Denchar.PlotWaveFunctions} must be .TRUE.
If set to .TRUE., file {\it SystemName}.WFSX should
be present.

{\it Default value:} .FALSE.
\end{description}



\vspace{5pt}
\subsection{Description of the 2D plane or 3D reference system}

\begin{description}
\itemsep 10pt
\parsep 0pt

\item[{\bf Denchar.CoorUnits}] ({\it string}): 
Character string to specify the format of the position of the points that
define the $xy$ plane in input.
These can be expressed in two forms:

\begin{itemize}
\item[-] Ang        : Angstroms 
\item[-] Bohr       : Bohrs
\end{itemize}

{\it Default value:} Bohr

\item[{\bf Denchar.DensityUnits}] ({\it string}): 
Character string to specify the units of the charge density in output. 
These can be expressed in three forms:

\begin{itemize}
\item[-] Ele/Bohr**3      : Electrons/bohr**3
\item[-] Ele/Ang**3       : Electrons/angstrom**3
\item[-] Ele/UnitCell     : Electrons/Unit Cell 
\end{itemize}

{\it Default value:} Ele/bohr**3

\item[{\bf Denchar.NumberPointsX}] ({\it integer}):
 Number of subdivision of the grid in the x-direction. Together
 with {\bf Denchar.NumberPointsY} (and {\bf Denchar.NumberPointsZ}
 for 3D mode), 
 it will define the 
 number of points of the grid to plot the charge density
 and/or wavefunctions.

{\it Default value:} 50

\item[{\bf Denchar.NumberPointsY}] ({\it integer}):
 Number of subdivision of the grid in the y-direction. Together
 with {\bf Denchar.NumberPointsX} (and {\bf Denchar.NumberPointsZ}
 for 3D mode), 
 it will define the 
 number of points of the grid to plot the charge density
 and/or wavefunctions.

{\it Default value:} 50

\item[{\bf Denchar.NumberPointsZ}] ({\it integer}):
 Number of subdivision of the grid in the z-direction. Together
 with {\bf Denchar.NumberPointsX} and {\bf Denchar.NumberPointsY}
 it defines the 
 number of points of the grid to plot the the charge density
 and/or wavefunctions.

{\it Use:} Only used if {\bf Denchar.TypeOfRun} = 3D

{\it Default value:} 50


\noindent 
 The next four variables define the size of the window inside the plane where
 we will focus our attention.

\item[{\bf Denchar.MinX}] ({\it real length}):
 Defines the minimum value of the x-component of the 2D or 3D grid,
 in the system or reference of the plotting plane (for 2D)
 or the 3D grid axes  (in 3D).

{\it Default value:} -3.0 bohrs

\item[{\bf Denchar.MaxX}] ({\it real length}):
 Defines the maximum value of the x-component of the 2D or 3D grid,
 in the system or reference of the plotting plane (for 2D)
 or the 3D grid axes  (in 3D).

{\it Default value:} +3.0 bohrs

\item[{\bf Denchar.MinY}] ({\it real length}):
 Defines the minimum value of the y-component of the 2D or 3D grid,
 in the system or reference of the plotting plane (for 2D)
 or the 3D grid axes  (in 3D).

{\it Default value:} -3.0 bohrs

\item[{\bf Denchar.MaxY}] ({\it real length}):
 Defines the maximum value of the y-component of the 2D or 3D grid,
 in the system or reference of the plotting plane (for 2D)
 or the 3D grid axes  (in 3D).

{\it Default value:} +3.0 bohrs

\item[{\bf Denchar.MinZ}] ({\it real length}):
 Defines the minimum value of the z-component of the 3D grid,
 in the system or reference of the 
 the 3D grid axes.

{\it Use:} Only used if {\bf Denchar.TypeOfRun} = 3D

{\it Default value:} -3.0 bohrs

\item[{\bf Denchar.MaxZ}] ({\it real length}):
 Defines the maximum value of the z-component of the 3D grid,
 in the system or reference of the 
 the 3D grid axes.

{\it Use:} Only used if {\bf Denchar.TypeOfRun} = 3D

{\it Default value:} +3.0 bohrs


\item[{\bf Denchar.PlaneGeneration}] ({\it string}): 
 Select the option to generate the $xy$ plane (which is
 the plane of the plot in 2D mode, and that defines the $x$-$y$
 axes in 3D mode).
 

\begin{itemize}
\item[-] NormalVector : If we want to choose the normal vector to describe the
                        plane.
\item[-] TwoLines       : If we want to specify two vectors contained in the 
                        plane.
\item[-] ThreePoints  : If we want to give the coordinates of three points 
                        of the plane.
\item[-] ThreeAtomicIndices : If we want the plane that contains three 
                        given atoms.
\end{itemize}
\noindent
{\it Default value:} {\tt NormalVector}


\item[{\bf Denchar.CompNormalVector}] ({\it data block}): 
Components of the normal vector. A normal vector defines a family of parallel
planes. So we must specify which of these planes is the one 
 we are interested in.
So, when we select the option {\it NormalVector} to generate the plane, we must 
also input the origin of our plane (one point lying on it), and another
point to define the x direction inside the plane (see below).

{\it Use:} Used only if {\bf Denchar.PlaneGeneration} is {\tt NormalVector}
    
{\it Default value:} 
\begin{verbatim}
  0.000   0.000   1.000
\end{verbatim}

\item[{\bf Denchar.Comp2Vectors}] ({\it data block}): 
Components of two vectors contained in the plane. 
The first vector defines the x direction inside the plane.
If {\bf Denchar.PlaneGeneration}={\it TwoLines} we must also supply the origin 
of the plane, {\it i.e.}  the coordinates of one point inside the plane (see
{\bf Denchar.PlaneOrigin} below). 

{\it Use:} Used only if {\bf Denchar.PlaneGeneration} is {\tt TwoLines}
    
{\it Default value:} 
\begin{verbatim}
  1.000   0.000   0.000
  0.000   1.000   0.000
\end{verbatim}

\item[{\bf Denchar.Coor3Points}] ({\it data block}): 
Coordinates of three points inside the plane. The first one will be taken
as the origin of the plane. The vector between the first and the second one 
will determine the x-direction inside the plane.

{\it Use:} Used only if {\bf Denchar.PlaneGeneration} is {\tt ThreePoints}
    
{\it Default value:} 
\begin{verbatim}
  1.000   0.000   0.000
  0.000   1.000   0.000
  0.000   0.000   1.000
\end{verbatim}

\item[{\bf Denchar.Indices3Atoms}] ({\it data block}): 
Indices of three atoms that will belong to the plane. In this way, we
define the plane that contains three given atoms. The coordinates
of the first atom are taken as the origin of the plane, 
and the vector between
the first and second atom will define the x-direction within
the plane.

{\it Use:} Used only if {\bf Denchar.PlaneGeneration}
is {\tt ThreeAtomicIndices}
    
{\it Default value:} 
\begin{verbatim}
  1 2 3
\end{verbatim}

\item[{\bf Denchar.PlaneOrigin}] ({\it data block}): 
Coordinates of one point inside the plane that will be taken as the origin. 
This is neccesary if we want to define the plane from the normal vector or
from two lines, because we must select one of the planes of the family of
parallel planes.

{\it Use:} Used only if {\bf Denchar.PlaneGeneration} is {\tt NormalVector} or
{\tt TwoLines}. If {\bf Denchar.PlaneGeneration} is {\tt ThreePoints}
or {\tt ThreeAtomicIndices}, the {\bf Denchar.PlaneOrigin} is
automaticaly chosen (see description of variables {\bf Denchar.Coor3Points}
and {\bf Denchar.Indices3Atoms}).
    
{\it Default value:} 
\begin{verbatim}
  0.000   0.000   0.000
\end{verbatim}
        
\item[{\bf Denchar.X-Axis}] ({\it data block}): 
Coordinates of one point inside the plane needed to define the x-direction,
when the normal vector is selected to define the plane. The vector between 
the origin and this new point will define the x-direction.

{\it Units:} bohrs.

{\it Use:} Used only if {\bf Denchar.PlaneGeneration} is {\tt NormalVector} 
    
{\it Default value:} 
\begin{verbatim}
  1.000   0.000   0.000
\end{verbatim}

\item[{\bf Denchar.AtomsInPlane}] ({\it data block}): 
Indices of the atoms whose coordinates will be rotated to the in-plane 
reference frame. In this system of reference, atoms in the plane will have 
the third coordinate equal to zero. 
The coordinates will be written in the corresponding output files. The
units of the output coordinates will be determined by {\bf Denchar.CoorUnits}.
One index per line.

{\it Default value:} No default value 

\end{description}

\section{OUTPUT FILES}
\label{cap:output} 

The output files produced by {\sc Denchar} depend on 
the mode of run (2D or 3D) and the quantities being plotted
(charge density and/or wavefunctions).

\subsection{2D mode}
\label{cap:output2D}

The output files generated in 2D mode runs have all the
same format: three 
columns, with the first two columns giving the coordinates of the points
in the plane (in the reference frame in which $x$ and $y$ are
contained in the plane), and
the third column gives the corresponding charge density or wavefunction
at that point. These can be used to draw contour maps or other 
2D graphic representations by means of standard graphics programs.
Depending on the physical quantity being plotted, 
different files are generated:

\subsubsection{Charge Density}

If the calculation is not spin-polarized,
two output files will be generated by {\sc Denchar}:

\begin{description}
\itemsep 10pt
\parsep 0pt

\item[{\bf {\it SystemLabel}.CON.SCF}]: 
Self-Consistent Charge Density at the points of the plane in real space.

\item[{\bf {\it SystemLabel}.CON.DEL}]: 
Difference between self-consistent charge density and the superposition
of atomic densities. 
 
\end{description}

If the calculation is spin-polarized, there are 
 four output files, namely:


\begin{description}
\itemsep 10pt
\parsep 0pt


\item[{\bf {\it SystemLabel}.CON.UP}]: 
Self-consistent charge density for electrons with spin UP.

\item[{\bf {\it SystemLabel}.CON.DOWN}]: 
Self-consistent charge density for electrons with spin DOWN.

\item[{\bf {\it SystemLabel}.CON.MAG}]: 
{\bf Magnetization}. Difference between self-consistent charge density 
with spin up and spin down.

\item[{\bf {\it SystemLabel}.CON.DEL}]: 
Difference between self-consistent charge density (equal to the 
sum of charge density for both spines) and the superposition
of atomic densities. 

\end{description}

\subsubsection{Wavefunctions}

{\sc Denchar} can plot the wavefunctions present in the
file {\tt SystemLabel}.WFSX generated by Siesta. For each
wavefunction, a different file will be created containing the values
of that wavefunction.  In what follows, the wave function number is
denoted by \#.

Wavefunctions can be selected by means of the \texttt{-k} and
\texttt{-w} command line arguments. For example,
\begin{verbatim}
   denchar -k 3 -w 4  file.fdf
\end{verbatim}

will plot only the wave-function with (original) index 4 of the third
k-point in the file.

If the calculation is not spin-polarized,
one output file will be generated by {\sc Denchar}
for each wavefunction:

\begin{description}
\itemsep 10pt
\parsep 0pt

\item[{\bf {\it SystemLabel}.CON.WF\#}]: 
Values of the wave function number \#

\end{description}

If the calculation is spin-polarized, there are 
 two output files, namely:


\begin{description}
\itemsep 10pt
\parsep 0pt

\item[{\bf {\it SystemLabel}.CON.WF\#.UP}]: 
Values of the wave function number \# with spin UP.

\item[{\bf {\it SystemLabel}.CON.WF\#.DOWN}]: 
Values of the wave function number \# with spin DOWN.

\end{description}

\subsection{3D mode}
\label{cap:output3D}

The output files generated in 3D mode runs have all the
same format: the Gaussian Cube format. The grid points and
atomic coordinates are given in the reference frame specified
by the input (not the one given by the  {\sc Siesta}
calculation). The reference frame is orthogonal.
These files can be used to draw 3D maps using programs
like  {\sc Molden} or {\sc Molekel}.
Depending on the physical quantity being plotted, 
different files are generated:

\subsubsection{Charge Density}

If the calculation is not spin-polarized,
two output files will be generated by {\sc Denchar}:

\begin{description}
\itemsep 10pt
\parsep 0pt

\item[{\bf {\it SystemLabel}.RHO.cube}]:
Self-Consistent Charge Density at the points of the 3D grid.

\item[{\bf {\it SystemLabel}.DRHO.cube}]:
Difference between self-consistent charge density and the superposition
of atomic densities.

\end{description}


If the calculation is spin-polarized,
five output files will be generated by {\sc Denchar}:

\begin{description}
\itemsep 10pt
\parsep 0pt

\item[{\bf {\it SystemLabel}.RHO.cube}]:
Total self-Consistent Charge Density of electrons (sum over spins)
at the points of the 3D grid.

\item[{\bf {\it SystemLabel}.RHO.UPminusDOWN.cube}]:
Difference between ``UP'' and ``DOWN'' self-consistent charge densities
at the points of the 3D grid.

\item[{\bf {\it SystemLabel}.RHO.UP.cube}]:
Self-Consistent Charge Density of electrons with spin UP,
at the points of the 3D grid.

\item[{\bf {\it SystemLabel}.RHO.DOWN.cube}]:
Self-Consistent Charge Density of electrons with spin DOWN,
at the points of the 3D grid.

\item[{\bf {\it SystemLabel}.DRHO.cube}]:
Difference between self-consistent charge density and the superposition
of atomic densities.

\end{description}

\subsubsection{Wavefunctions}

{\sc Denchar} plots each of the wavefunctions that is
present in the file {\tt SystemLabel}.WFSX generated
by Siesta. For each wavefunction, a different file
will be created containing the values of that wavefunction.
In what follows, the wave function number is denoted by
\#.

If the calculation is not spin-polarized,
one output file will be generated by {\sc Denchar}
for each wavefunction:

\begin{description}
\itemsep 10pt
\parsep 0pt

\item[{\bf {\it SystemLabel}.WF\#.cube}]: 
Values of the wave function number \# in the 3D grid.

\end{description}

If the calculation is spin-polarized, there are 
 two output files, namely:


\begin{description}
\itemsep 10pt
\parsep 0pt

\item[{\bf {\it SystemLabel}.WF\#.UP.cube}]: 
Values of the wave function number \# with spin UP.

\item[{\bf {\it SystemLabel}.WF\#.DOWN.cube}]: 
Values of the wave function number \# with spin DOWN.

\end{description}

\section{EXAMPLES}

In directory {\tt $\sim$/siesta/Util/Denchar/Examples} you will find some
examples of input files for the different options. The physical system is a
cell of Si in the diamond structure at the experimental lattice constant.

\end{document}
